home *** CD-ROM | disk | FTP | other *** search
/ Teach Yourself VRML 2 in 21 Days / Teach Yourself VRML 2 in 21 Days.iso / mac / ISO9660 / 3rdparty / POLYTRAN / dos / PT_DOS.ZIP / DOC_1 / IMP_WAVE.1 < prev    next >
Encoding:
Text File  |  1996-07-27  |  8.5 KB  |  167 lines
  1. .so psroff.inc        # Include the macros needed for output to Postscript
  2. .TH Import-Wavefront
  3. .SH NAME
  4. imp_wavefront \- Wavefront .OBJ geometry import filter
  5. .SH SYNOPSIS
  6. .PP
  7. This man page describes the options specific to the Wavefront .OBJ geometry
  8. import converter.
  9. .PP
  10. .SH EXAMPLE CONVERSION SYNTAX
  11. .PP
  12. To convert a Wavefront file to 3D Studio using the default parameters listed 
  13. in the setup.ini file:
  14. .IP
  15. pt -i wave -o 3ds filename.obj
  16. .PP
  17. To convert a Wavefront file to VRML and override some of the default options 
  18. in setup.ini:
  19. .IP
  20. pt -i wave -in-wave-print-stats = yes -o 3ds filename.obj
  21. .PP
  22. .SH OVERVIEW
  23. .PP
  24. This geometry import converter reads in Wavefront 'OBJ' format files in their 
  25. entirety, including vertex, normal and texture coordinates, as well as 
  26. grouping and smoothing information. Many companies which sell 3D models 
  27. provide their datasets in the OBJ file format, so you can use this converter 
  28. to read in these data files and be guaranteed nice rendered results. 
  29. .PP
  30. The converter will also read material definitions from a Wavefront material
  31. file (typically which has a file extension '.mtl') if the material file
  32. is referenced within the Wavefront geometry file (typically which has a 
  33. file extension '.obj') using the 'mtllib' keyword. If one or more Wavefront
  34. material files are listed on a single line then all will be read into
  35. memory for possible reference by the geometry file.
  36. .PP
  37. The converter first reads the entire file into memory; this includes the 
  38. vertex, normal and texture coordinate lists, their indice lists, all group 
  39. names, material names and texture names, and the smoothing groups assigned to 
  40. each polygon. Next, the converter computes new vertex normals for polygons 
  41. that don't have any normals and that have a non-zero smoothing group assigned to 
  42. them. If no smoothing groups are found then the converter optionally creates 
  43. smoothed vertex normals based on the angle between abutting polygon faces. As a 
  44. last step, the polygonal data is separated into separate objects based on 
  45. a user-chosen criteria.
  46. .PP
  47. .SH NOTES:
  48. .IP
  49. If any texture map names are found in the file (ie: if the 'usemap <map_name>'
  50. command is specified in the file) and the '-in-wave-surf-name-src' option 
  51. of this converter is set to 'use-mat-name' then texture definitions will be 
  52. automatically created for these texture names and will be assigned to their 
  53. corresponding surfaces. NOTE:: you can distinguish these textured surfaces because 
  54. the texture map name is appended to the end of the surface name (the surface and 
  55. texture names are separated by three underscores '_').
  56. .IP
  57. If one or more group names are found on a 'g' line then they are appended all 
  58. together to form the group name used internally (ie: 'g all airplane tail_fin').
  59. .PP
  60. .SH COMMAND LINE OPTIONS
  61. .PP
  62. The following options are specific to this import converter:
  63. .TP
  64. -i wave
  65. This is the optional command line option which specifies that the input data
  66. is in the Wavefront .OBJ file format. If not specified then the converter will try 
  67. to guess the input file's format from its file extension (.obj) and then from the 
  68. contents of its file. 
  69. .TP
  70. -in-wave-do-smoothing = [ yes | no ]
  71. If set to 'yes' then new vertex normals will be automatically computed for a 
  72. polygon based on the smoothing group numbers located within the .OBJ file.
  73. Note: if explicit vertex normals are already associated with a specific polygon
  74. then automatically generated normals will not be computed for that polygon. Also
  75. note that for smoothing to take place two or more polygons must be abutting and 
  76. share the same vertices.
  77. .TP
  78. -in-wave-compute-avg-normals = [ yes | no ]
  79. If set to 'yes' then new vertex normals will be computed for a polygon if it 
  80. does not already have any vertex normals, and it does not have a smoothing 
  81. group assigned to it or the '-in-wave-do-smoothing' option described above is
  82. set to 'no. The smoothing criterion is based on the angle between abutting 
  83. polygons; smoothed vertex normals will be computed if the angle 
  84. between two polygons' geometric surfaces normals is less than the angle specified
  85. with the '-in-wave-smoothing-angle' option described below.
  86. .TP
  87. -in-wave-smoothing-angle = #
  88. This option sets the cut-off smoothing angle (in degrees) used by the vertex normal
  89. computation algorithm. If the angle between two abutting polygons is greater
  90. than this number then no smoothing will occur (a crease will be evident
  91. between the two polygons), else smoothing will occur where the polygons
  92. meet. The default angle is 30 degrees.
  93. .TP
  94. -in-wave-print-stats = [ yes | no ]
  95. If set to 'yes' then statistics about the geometry file will be reported 
  96. once it has been read in and processed.
  97. .TP
  98. -in-wave-print-warn
  99. If set to 'yes' then warning messages will be reported as the file is read in. 
  100. Warnings include unrecognized input and options, out-of-range texture 
  101. coordinates and out-of-range index values.
  102. .TP
  103. -in-wave-surf-name-src = [ use-mat-else-group-name | use-mat-name | use-group-name | use-object-name ]
  104. .IP
  105. This option specifies which method the converter is to use to assign a surface 
  106. definition (a material) to each polygon. Automatic assignment of surfaces to 
  107. the polygons will save you a lot of time and headache.
  108. .IP
  109. The 'use-mat-else-group-name' option uses the material name found in the
  110. file as the new surface name, else it uses the group name as the new surface
  111. name, else if uses the object name as the new surface name
  112.  if no material name is associated with the current polygon(s). 
  113. If no material or group name is assigned then the "default" surface will be 
  114. used. This option is the default.
  115. .IP
  116. The 'use-mat-name' option uses the material name found in file, else it
  117. uses the "default" surface if no material name is found. 
  118. .IP
  119. The 'use-group-name' option uses the group name found in the file, else it
  120. uses the "default" surface if no group name is found. 
  121. .IP
  122. The 'use-object-name' option uses the object name found in the file, else it
  123. uses the "default" surface if no object name is found. 
  124. .TP
  125. -in-wave-split-method = [ off | by-group-name | by-object-name | by-mat-name | by-txtr-name | by-smoothing-num ]
  126. .IP
  127. This option selects which criterion is to be used when the polygonal data is 
  128. to be split up into different objects. If your 3D scene is going to have many 
  129. different objects in it then it is recommended that the OBJ not be split up. 
  130. However, if you want to modify each individual part in the OBJ file then you 
  131. will want to split it up into different objects.
  132. .IP
  133. The 'off' option disables the OBJ file from being split up into separate 
  134. objects.
  135. .IP
  136. The 'by-group-name' option will split the polygonal geometry according to the 
  137. group name assigned to each polygon. It is the most logical method for 
  138. splitting the geometry since the group names are usually assigned on an 
  139. object-name basis by the person who designed the 3D model. Groups are 
  140. assigned to polygons in the OBJ file by preceding them with a line like: 
  141. 'g <group_name1> ... <group_nameN>'. 
  142. .IP
  143. The 'by-object-name' option will split the polygonal geometry according to the 
  144. object name assigned to each polygon. Groups are 
  145. assigned to polygons in the OBJ file by preceding them with a line like: 
  146. 'o <object_name>'.
  147. .IP
  148. The 'by-mat-name' option will split the polygonal geometry according to the 
  149. material name assigned to each polygon. You may want to use this method if no 
  150. group names are provided in the file or if it makes more sense to split by 
  151. material name than by group name (for example, the object might have 300 odd 
  152. group names but 20 carefully chosen material names). Materials are assigned 
  153. to polygons in the OBJ file by preceding them with a line like: 'usemtl <material_name>'.
  154. .IP
  155. The 'by-txtr-name' option will split the polygonal geometry according to the 
  156. texture map name assigned to each polygon. In most cases you will not use this 
  157. method. Texture map names are assigned to polygons in the OBJ file by preceding 
  158. them with a line like: 'usemap <texture_map_name>'.
  159. .IP
  160. The 'by-smoothing-num' option will split the polygonal geometry according to 
  161. the smoothing group number assigned to each polygon. Since smoothed polygons 
  162. are usually clustered together as one sub-object this method can be used to 
  163. accurately extract sub-objects from the polygonal data. However, it will 
  164. probably create many more new objects than would the 'by-group-name' method 
  165. above. Smoothing groups are assigned to polygons in the OBJ file by preceding 
  166. them with a line like: 's <smoothing_number>'.
  167.